home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
SGI Freeware 1998 November
/
Freeware November 1998.img
/
dist
/
fw_elisp-manual-19.idb
/
usr
/
freeware
/
info
/
elisp-15.z
/
elisp-15
(
.txt
)
Wrap
GNU Info File
|
1998-05-26
|
51KB
|
948 lines
This is Info file elisp, produced by Makeinfo-1.63 from the input file
elisp.texi.
This version is the edition 2.4.2 of the GNU Emacs Lisp Reference
Manual. It corresponds to Emacs Version 19.34.
Published by the Free Software Foundation 59 Temple Place, Suite 330
Boston, MA 02111-1307 USA
Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996 Free Software
Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU General Public License" is included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the section entitled "GNU General Public License"
may be included in a translation approved by the Free Software
Foundation instead of in the original English.
File: elisp, Node: Using Interactive, Next: Interactive Codes, Up: Defining Commands
Using `interactive'
-------------------
This section describes how to write the `interactive' form that
makes a Lisp function an interactively-callable command.
- Special Form: interactive ARG-DESCRIPTOR
This special form declares that the function in which it appears
is a command, and that it may therefore be called interactively
(via `M-x' or by entering a key sequence bound to it). The
argument ARG-DESCRIPTOR declares how to compute the arguments to
the command when the command is called interactively.
A command may be called from Lisp programs like any other
function, but then the caller supplies the arguments and
ARG-DESCRIPTOR has no effect.
The `interactive' form has its effect because the command loop
(actually, its subroutine `call-interactively') scans through the
function definition looking for it, before calling the function.
Once the function is called, all its body forms including the
`interactive' form are executed, but at this time `interactive'
simply returns `nil' without even evaluating its argument.
There are three possibilities for the argument ARG-DESCRIPTOR:
* It may be omitted or `nil'; then the command is called with no
arguments. This leads quickly to an error if the command requires
one or more arguments.
* It may be a Lisp expression that is not a string; then it should
be a form that is evaluated to get a list of arguments to pass to
the command.
If this expression reads keyboard input (this includes using the
minibuffer), keep in mind that the integer value of point or the
mark before reading input may be incorrect after reading input.
This is because the current buffer may be receiving subprocess
output; if subprocess output arrives while the command is waiting
for input, it could relocate point and the mark.
Here's an example of what *not* to do:
(interactive
(list (region-beginning) (region-end)
(read-string "Foo: " nil 'my-history)))
Here's how to avoid the problem, by examining point and the mark
only after reading the keyboard input:
(interactive
(let ((string (read-string "Foo: " nil 'my-history)))
(list (region-beginning) (region-end) string)))
* It may be a string; then its contents should consist of a code
character followed by a prompt (which some code characters use and
some ignore). The prompt ends either with the end of the string
or with a newline. Here is a simple example:
(interactive "bFrobnicate buffer: ")
The code letter `b' says to read the name of an existing buffer,
with completion. The buffer name is the sole argument passed to
the command. The rest of the string is a prompt.
If there is a newline character in the string, it terminates the
prompt. If the string does not end there, then the rest of the
string should contain another code character and prompt,
specifying another argument. You can specify any number of
arguments in this way.
The prompt string can use `%' to include previous argument values
(starting with the first argument) in the prompt. This is done
using `format' (*note Formatting Strings::.). For example, here
is how you could read the name of an existing buffer followed by a
new name to give to that buffer:
(interactive "bBuffer to rename: \nsRename buffer %s to: ")
If the first character in the string is `*', then an error is
signaled if the buffer is read-only.
If the first character in the string is `@', and if the key
sequence used to invoke the command includes any mouse events, then
the window associated with the first of those events is selected
before the command is run.
You can use `*' and `@' together; the order does not matter.
Actual reading of arguments is controlled by the rest of the prompt
string (starting with the first character that is not `*' or `@').
File: elisp, Node: Interactive Codes, Next: Interactive Examples, Prev: Using Interactive, Up: Defining Commands
Code Characters for `interactive'
---------------------------------
The code character descriptions below contain a number of key words,
defined here as follows:
Completion
Provide completion. TAB, SPC, and RET perform name completion
because the argument is read using `completing-read' (*note
Completion::.). `?' displays a list of possible completions.
Existing
Require the name of an existing object. An invalid name is not
accepted; the commands to exit the minibuffer do not exit if the
current input is not valid.
Default
A default value of some sort is used if the user enters no text in
the minibuffer. The default depends on the code character.
No I/O
This code letter computes an argument without reading any input.
Therefore, it does not use a prompt string, and any prompt string
you supply is ignored.
Even though the code letter doesn't use a prompt string, you must
follow it with a newline if it is not the last code character in
the string.
Prompt
A prompt immediately follows the code character. The prompt ends
either with the end of the string or with a newline.
Special
This code character is meaningful only at the beginning of the
interactive string, and it does not look for a prompt or a newline.
It is a single, isolated character.
Here are the code character descriptions for use with `interactive':
Signal an error if the current buffer is read-only. Special.
Select the window mentioned in the first mouse event in the key
sequence that invoked this command. Special.
A function name (i.e., a symbol satisfying `fboundp'). Existing,
Completion, Prompt.
The name of an existing buffer. By default, uses the name of the
current buffer (*note Buffers::.). Existing, Completion, Default,
Prompt.
A buffer name. The buffer need not exist. By default, uses the
name of a recently used buffer other than the current buffer.
Completion, Default, Prompt.
A character. The cursor does not move into the echo area. Prompt.
A command name (i.e., a symbol satisfying `commandp'). Existing,
Completion, Prompt.
The position of point, as an integer (*note Point::.). No I/O.
A directory name. The default is the current default directory of
the current buffer, `default-directory' (*note System
Environment::.). Existing, Completion, Default, Prompt.
The first or next mouse event in the key sequence that invoked the
command. More precisely, `e' gets events that are lists, so you
can look at the data in the lists. *Note Input Events::. No I/O.
You can use `e' more than once in a single command's interactive
specification. If the key sequence that invoked the command has N
events that are lists, the Nth `e' provides the Nth such event.
Events that are not lists, such as function keys and ASCII
characters, do not count where `e' is concerned.
A file name of an existing file (*note File Names::.). The default
directory is `default-directory'. Existing, Completion, Default,
Prompt.
A file name. The file need not exist. Completion, Default,
Prompt.
A key sequence (*note Keymap Terminology::.). This keeps reading
events until a command (or undefined command) is found in the
current key maps. The key sequence argument is represented as a
string or vector. The cursor does not move into the echo area.
Prompt.
This kind of input is used by commands such as `describe-key' and
`global-set-key'.
A key sequence, whose definition you intend to change. This works
like `k', except that it suppresses, for the last input event in
the key sequence, the conversions that are normally used (when
necessary) to convert an undefined key into a defined one.
The position of the mark, as an integer. No I/O.
A number read with the minibuffer. If the input is not a number,
the user is asked to try again. The prefix argument, if any, is
not used. Prompt.
The numeric prefix argument; but if there is no prefix argument,
read a number as with `n'. Requires a number. *Note Prefix
Command Arguments::. Prompt.
The numeric prefix argument. (Note that this `p' is lower case.)
No I/O.
The raw prefix argument. (Note that this `P' is upper case.) No
I/O.
Point and the mark, as two numeric arguments, smallest first.
This is the only code letter that specifies two successive
arguments rather than one. No I/O.
Arbitrary text, read in the minibuffer and returned as a string
(*note Text from Minibuffer::.). Terminate the input with either
LFD or RET. (`C-q' may be used to include either of these
characters in the input.) Prompt.
An interned symbol whose name is read in the minibuffer. Any
whitespace character terminates the input. (Use `C-q' to include
whitespace in the string.) Other characters that normally
terminate a symbol (e.g., parentheses and brackets) do not do so
here. Prompt.
A variable declared to be a user option (i.e., satisfying the
predicate `user-variable-p'). *Note High-Level Completion::.
Existing, Completion, Prompt.
A Lisp object, specified with its read syntax, terminated with a
LFD or RET. The object is not evaluated. *Note Object from
Minibuffer::. Prompt.
A Lisp form is read as with `x', but then evaluated so that its
value becomes the argument for the command. Prompt.
File: elisp, Node: Interactive Examples, Prev: Interactive Codes, Up: Defining Commands
Examples of Using `interactive'
-------------------------------
Here are some examples of `interactive':
(defun foo1 () ; `foo1' takes no arguments,
(interactive) ; just moves forward two words.
(forward-word 2))
=> foo1
(defun foo2 (n) ; `foo2' takes one argument,
(interactive "p") ; which is the numeric prefix.
(forward-word (* 2 n)))
=> foo2
(defun foo3 (n) ; `foo3' takes one argument,
(interactive "nCount:") ; which is read with the Minibuffer.
(forward-word (* 2 n)))
=> foo3
(defun three-b (b1 b2 b3)
"Select three existing buffers.
Put them into three windows, selecting the last one."
(interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
(delete-other-windows)
(split-window (selected-window) 8)
(switch-to-buffer b1)
(other-window 1)
(split-window (selected-window) 8)
(switch-to-buffer b2)
(other-window 1)
(switch-to-buffer b3))
=> three-b
(three-b "*scratch*" "declarations.texi" "*mail*")
=> nil
File: elisp, Node: Interactive Call, Next: Command Loop Info, Prev: Defining Commands, Up: Command Loop
Interactive Call
================
After the command loop has translated a key sequence into a
definition, it invokes that definition using the function
`command-execute'. If the definition is a function that is a command,
`command-execute' calls `call-interactively', which reads the arguments
and calls the command. You can also call these functions yourself.
- Function: commandp OBJECT
Returns `t' if OBJECT is suitable for calling interactively; that
is, if OBJECT is a command. Otherwise, returns `nil'.
The interactively callable objects include strings and vectors
(treated as keyboard macros), lambda expressions that contain a
top-level call to `interactive', byte-code function objects made
from such lambda expressions, autoload objects that are declared
as interactive (non-`nil' fourth argument to `autoload'), and some
of the primitive functions.
A symbol is `commandp' if its function definition is `commandp'.
Keys and keymaps are not commands. Rather, they are used to look
up commands (*note Keymaps::.).
See `documentation' in *Note Accessing Documentation::, for a
realistic example of using `commandp'.
- Function: call-interactively COMMAND &optional RECORD-FLAG
This function calls the interactively callable function COMMAND,
reading arguments according to its interactive calling
specifications. An error is signaled if COMMAND is not a function
or if it cannot be called interactively (i.e., is not a command).
Note that keyboard macros (strings and vectors) are not accepted,
even though they are considered commands, because they are not
functions.
If RECORD-FLAG is non-`nil', then this command and its arguments
are unconditionally added to the list `command-history'.
Otherwise, the command is added only if it uses the minibuffer to
read an argument. *Note Command History::.
- Function: command-execute COMMAND &optional RECORD-FLAG
This function executes COMMAND as an editing command. The
argument COMMAND must satisfy the `commandp' predicate; i.e., it
must be an interactively callable function or a keyboard macro.
A string or vector as COMMAND is executed with
`execute-kbd-macro'. A function is passed to
`call-interactively', along with the optional RECORD-FLAG.
A symbol is handled by using its function definition in its place.
A symbol with an `autoload' definition counts as a command if it
was declared to stand for an interactively callable function.
Such a definition is handled by loading the specified library and
then rechecking the definition of the symbol.
- Command: execute-extended-command PREFIX-ARGUMENT
This function reads a command name from the minibuffer using
`completing-read' (*note Completion::.). Then it uses
`command-execute' to call the specified command. Whatever that
command returns becomes the value of `execute-extended-command'.
If the command asks for a prefix argument, it receives the value
PREFIX-ARGUMENT. If `execute-extended-command' is called
interactively, the current raw prefix argument is used for
PREFIX-ARGUMENT, and thus passed on to whatever command is run.
`execute-extended-command' is the normal definition of `M-x', so
it uses the string `M-x ' as a prompt. (It would be better to
take the prompt from the events used to invoke
`execute-extended-command', but that is painful to implement.) A
description of the value of the prefix argument, if any, also
becomes part of the prompt.
(execute-extended-command 1)
---------- Buffer: Minibuffer ----------
1 M-x forward-word RET
---------- Buffer: Minibuffer ----------
=> t
- Function: interactive-p
This function returns `t' if the containing function (the one whose
code includes the call to `interactive-p') was called
interactively, with the function `call-interactively'. (It makes
no difference whether `call-interactively' was called from Lisp or
directly from the editor command loop.) If the containing
function was called by Lisp evaluation (or with `apply' or
`funcall'), then it was not called interactively.
The most common use of `interactive-p' is for deciding whether to
print an informative message. As a special exception,
`interactive-p' returns `nil' whenever a keyboard macro is being
run. This is to suppress the informative messages and speed
execution of the macro.
For example:
(defun foo ()
(interactive)
(and (interactive-p)
(message "foo")))
=> foo
(defun bar ()
(interactive)
(setq foobar (list (foo) (interactive-p))))
=> bar
;; Type `M-x foo'.
-| foo
;; Type `M-x bar'.
;; This does not print anything.
foobar
=> (nil t)
File: elisp, Node: Command Loop Info, Next: Input Events, Prev: Interactive Call, Up: Command Loop
Information from the Command Loop
=================================
The editor command loop sets several Lisp variables to keep status
records for itself and for commands that are run.
- Variable: last-command
This variable records the name of the previous command executed by
the command loop (the one before the current command). Normally
the value is a symbol with a function definition, but this is not
guaranteed.
The value is copied from `this-command' when a command returns to
the command loop, except when the command specifies a prefix
argument for the following command.
This variable is always local to the current terminal and cannot be
buffer-local. *Note Multiple Displays::.
- Variable: this-command
This variable records the name of the command now being executed by
the editor command loop. Like `last-command', it is normally a
symbol with a function definition.
The command loop sets this variable just before running a command,
and copies its value into `last-command' when the command finishes
(unless the command specifies a prefix argument for the following
command).
Some commands set this variable during their execution, as a flag
for whatever command runs next. In particular, the functions for
killing text set `this-command' to `kill-region' so that any kill
commands immediately following will know to append the killed text
to the previous kill.
If you do not want a particular command to be recognized as the
previous command in the case where it got an error, you must code that
command to prevent this. One way is to set `this-command' to `t' at the
beginning of the command, and set `this-command' back to its proper
value at the end, like this:
(defun foo (args...)
(interactive ...)
(let ((old-this-command this-command))
(setq this-command t)
...do the work...
(setq this-command old-this-command)))
- Function: this-command-keys
This function returns a string or vector containing the key
sequence that invoked the present command, plus any previous
commands that generated the prefix argument for this command. The
value is a string if all those events were characters. *Note
Input Events::.
(this-command-keys)
;; Now use `C-u C-x C-e' to evaluate that.
=> "^U^X^E"
- Variable: last-nonmenu-event
This variable holds the last input event read as part of a key
sequence, not counting events resulting from mouse menus.
One use of this variable is to figure out a good default location
to pop up another menu.
- Variable: last-command-event
- Variable: last-command-char
This variable is set to the last input event that was read by the
command loop as part of a command. The principal use of this
variable is in `self-insert-command', which uses it to decide which
character to insert.
last-command-event
;; Now use `C-u C-x C-e' to evaluate that.
=> 5
The value is 5 because that is the ASCII code for `C-e'.
The alias `last-command-char' exists for compatibility with Emacs
version 18.
- Variable: last-event-frame
This variable records which frame the last input event was
directed to. Usually this is the frame that was selected when the
event was generated, but if that frame has redirected input focus
to another frame, the value is the frame to which the event was
redirected. *Note Input Focus::.
File: elisp, Node: Input Events, Next: Reading Input, Prev: Command Loop Info, Up: Command Loop
Input Events
============
The Emacs command loop reads a sequence of "input events" that
represent keyboard or mouse activity. The events for keyboard activity
are characters or symbols; mouse events are always lists. This section
describes the representation and meaning of input events in detail.
- Function: eventp OBJECT
This function returns non-`nil' if OBJECT is an input event.
* Menu:
* Keyboard Events:: Ordinary characters-keys with symbols on them.
* Function Keys:: Function keys-keys with names, not symbols.
* Mouse Events:: Overview of mouse events.
* Click Events:: Pushing and releasing a mouse button.
* Drag Events:: Moving the mouse before releasing the button.
* Button-Down Events:: A button was pushed and not yet released.
* Repeat Events:: Double and triple click (or drag, or down).
* Motion Events:: Just moving the mouse, not pushing a button.
* Focus Events:: Moving the mouse between frames.
* Misc Events:: Other events window systems can generate.
* Event Examples:: Examples of the lists for mouse events.
* Classifying Events:: Finding the modifier keys in an event symbol.
Event types.
* Accessing Events:: Functions to extract info from events.
* Strings of Events:: Special considerations for putting
keyboard character events in a string.
File: elisp, Node: Keyboard Events, Next: Function Keys, Up: Input Events
Keyboard Events
---------------
There are two kinds of input you can get from the keyboard: ordinary
keys, and function keys. Ordinary keys correspond to characters; the
events they generate are represented in Lisp as characters. In Emacs
versions 18 and earlier, characters were the only events. The event
type of a character event is the character itself (an integer); see
*Note Classifying Events::.
An input character event consists of a "basic code" between 0 and
255, plus any or all of these "modifier bits":
The 2**27 bit in the character code indicates a character typed
with the meta key held down.
control
The 2**26 bit in the character code indicates a non-ASCII control
character.
ASCII control characters such as `C-a' have special basic codes of
their own, so Emacs needs no special bit to indicate them. Thus,
the code for `C-a' is just 1.
But if you type a control combination not in ASCII, such as `%'
with the control key, the numeric value you get is the code for
`%' plus 2**26 (assuming the terminal supports non-ASCII control
characters).
shift
The 2**25 bit in the character code indicates an ASCII control
character typed with the shift key held down.
For letters, the basic code indicates upper versus lower case; for
digits and punctuation, the shift key selects an entirely different
character with a different basic code. In order to keep within
the ASCII character set whenever possible, Emacs avoids using the
2**25 bit for those characters.
However, ASCII provides no way to distinguish `C-A' from `C-a', so
Emacs uses the 2**25 bit in `C-A' and not in `C-a'.
hyper
The 2**24 bit in the character code indicates a character typed
with the hyper key held down.
super
The 2**23 bit in the character code indicates a character typed
with the super key held down.
The 2**22 bit in the character code indicates a character typed
with the alt key held down. (On some terminals, the key labeled
ALT is actually the meta key.)
It is best to avoid mentioning specific bit numbers in your program.
To test the modifier bits of a character, use the function
`event-modifiers' (*note Classifying Events::.). When making key
bindings, you can use the read syntax for characters with modifier bits
(`\C-', `\M-', and so on). For making key bindings with `define-key',
you can use lists such as `(control hyper ?x)' to specify the
characters (*note Changing Key Bindings::.). The function
`event-convert-list' converts such a list into an event type (*note
Classifying Events::.).
File: elisp, Node: Function Keys, Next: Mouse Events, Prev: Keyboard Events, Up: Input Events
Function Keys
-------------
Most keyboards also have "function keys"--keys that have names or
symbols that are not characters. Function keys are represented in Lisp
as symbols; the symbol's name is the function key's label, in lower
case. For example, pressing a key labeled F1 places the symbol `f1' in
the input stream.
The event type of a function key event is the event symbol itself.
*Note Classifying Events::.
Here are a few special cases in the symbol-naming convention for
function keys:
`backspace', `tab', `newline', `return', `delete'
These keys correspond to common ASCII control characters that have
special keys on most keyboards.
In ASCII, `C-i' and TAB are the same character. If the terminal
can distinguish between them, Emacs conveys the distinction to
Lisp programs by representing the former as the integer 9, and the
latter as the symbol `tab'.
Most of the time, it's not useful to distinguish the two. So
normally `function-key-map' (*note Translating Input::.) is set up
to map `tab' into 9. Thus, a key binding for character code 9 (the
character `C-i') also applies to `tab'. Likewise for the other
symbols in this group. The function `read-char' likewise converts
these events into characters.
In ASCII, BS is really `C-h'. But `backspace' converts into the
character code 127 (DEL), not into code 8 (BS). This is what most
users prefer.
`left', `up', `right', `down'
Cursor arrow keys
`kp-add', `kp-decimal', `kp-divide', ...
Keypad keys (to the right of the regular keyboard).
`kp-0', `kp-1', ...
Keypad keys with digits.
`kp-f1', `kp-f2', `kp-f3', `kp-f4'
Keypad PF keys.
`kp-home', `kp-left', `kp-up', `kp-right', `kp-down'
Keypad arrow keys. Emacs normally translates these into the
non-keypad keys `home', `left', ...
`kp-prior', `kp-next', `kp-end', `kp-begin', `kp-insert', `kp-delete'
Additional keypad duplicates of keys ordinarily found elsewhere.
Emacs normally translates these into the like-named non-keypad
keys.
You can use the modifier keys ALT, CTRL, HYPER, META, SHIFT, and
SUPER with function keys. The way to represent them is with prefixes
in the symbol name:
The alt modifier.
The control modifier.
The hyper modifier.
The meta modifier.
The shift modifier.
The super modifier.
Thus, the symbol for the key F3 with META held down is `M-f3'. When
you use more than one prefix, we recommend you write them in
alphabetical order; but the order does not matter in arguments to the
key-binding lookup and modification functions.
File: elisp, Node: Mouse Events, Next: Click Events, Prev: Function Keys, Up: Input Events
Mouse Events
------------
Emacs supports four kinds of mouse events: click events, drag events,
button-down events, and motion events. All mouse events are represented
as lists. The CAR of the list is the event type; this says which mouse
button was involved, and which modifier keys were used with it. The
event type can also distinguish double or triple button presses (*note
Repeat Events::.). The rest of the list elements give position and
time information.
For key lookup, only the event type matters: two events of the same
type necessarily run the same command. The command can access the full
values of these events using the `e' interactive code. *Note
Interactive Codes::.
A key sequence that starts with a mouse event is read using the
keymaps of the buffer in the window that the mouse was in, not the
current buffer. This does not imply that clicking in a window selects
that window or its buffer--that is entirely under the control of the
command binding of the key sequence.
File: elisp, Node: Click Events, Next: Drag Events, Prev: Mouse Events, Up: Input Events
Click Events
------------
When the user presses a mouse button and releases it at the same
location, that generates a "click" event. Mouse click events have this
form:
(EVENT-TYPE
(WINDOW BUFFER-POS (X . Y) TIMESTAMP)
CLICK-COUNT)
Here is what the elements normally mean:
EVENT-TYPE
This is a symbol that indicates which mouse button was used. It is
one of the symbols `mouse-1', `mouse-2', ..., where the buttons
are numbered left to right.
You can also use prefixes `A-', `C-', `H-', `M-', `S-' and `s-'
for modifiers alt, control, hyper, meta, shift and super, just as
you would with function keys.
This symbol also serves as the event type of the event. Key
bindings describe events by their types; thus, if there is a key
binding for `mouse-1', that binding would apply to all events whose
EVENT-TYPE is `mouse-1'.
WINDOW
This is the window in which the click occurred.
These are the pixel-denominated coordinates of the click, relative
to the top left corner of WINDOW, which is `(0 . 0)'.
BUFFER-POS
This is the buffer position of the character clicked on.
TIMESTAMP
This is the time at which the event occurred, in milliseconds.
(Since this value wraps around the entire range of Emacs Lisp
integers in about five hours, it is useful only for relating the
times of nearby events.)
CLICK-COUNT
This is the number of rapid repeated presses so far of the same
mouse button. *Note Repeat Events::.
The meanings of BUFFER-POS, X and Y are somewhat different when the
event location is in a special part of the screen, such as the mode
line or a scroll bar.
If the location is in a scroll bar, then BUFFER-POS is the symbol
`vertical-scroll-bar' or `horizontal-scroll-bar', and the pair `(X .
Y)' is replaced with a pair `(PORTION . WHOLE)', where PORTION is the
distance of the click from the top or left end of the scroll bar, and
WHOLE is the length of the entire scroll bar.
If the position is on a mode line or the vertical line separating
WINDOW from its neighbor to the right, then BUFFER-POS is the symbol
`mode-line' or `vertical-line'. For the mode line, Y does not have
meaningful data. For the vertical line, X does not have meaningful
data.
In one special case, BUFFER-POS is a list containing a symbol (one
of the symbols listed above) instead of just the symbol. This happens
after the imaginary prefix keys for the event are inserted into the
input stream. *Note Key Sequence Input::.
File: elisp, Node: Drag Events, Next: Button-Down Events, Prev: Click Events, Up: Input Events
Drag Events
-----------
With Emacs, you can have a drag event without even changing your
clothes. A "drag event" happens every time the user presses a mouse
button and then moves the mouse to a different character position before
releasing the button. Like all mouse events, drag events are
represented in Lisp as lists. The lists record both the starting mouse
position and the final position, like this:
(EVENT-TYPE
(WINDOW1 BUFFER-POS1 (X1 . Y1) TIMESTAMP1)
(WINDOW2 BUFFER-POS2 (X2 . Y2) TIMESTAMP2)
CLICK-COUNT)
For a drag event, the name of the symbol EVENT-TYPE contains the
prefix `drag-'. The second and third elements of the event give the
starting and ending position of the drag. Aside from that, the data
have the same meanings as in a click event (*note Click Events::.). You
can access the second element of any mouse event in the same way, with
no need to distinguish drag events from others.
The `drag-' prefix follows the modifier key prefixes such as `C-'
and `M-'.
If `read-key-sequence' receives a drag event that has no key
binding, and the corresponding click event does have a binding, it
changes the drag event into a click event at the drag's starting
position. This means that you don't have to distinguish between click
and drag events unless you want to.
File: elisp, Node: Button-Down Events, Next: Repeat Events, Prev: Drag Events, Up: Input Events
Button-Down Events
------------------
Click and drag events happen when the user releases a mouse button.
They cannot happen earlier, because there is no way to distinguish a
click from a drag until the button is released.
If you want to take action as soon as a button is pressed, you need
to handle "button-down" events.(1) These occur as soon as a button is
pressed. They are represented by lists that look exactly like click
events (*note Click Events::.), except that the EVENT-TYPE symbol name
contains the prefix `down-'. The `down-' prefix follows modifier key
prefixes such as `C-' and `M-'.
The function `read-key-sequence', and therefore the Emacs command
loop as well, ignore any button-down events that don't have command
bindings. This means that you need not worry about defining button-down
events unless you want them to do something. The usual reason to define
a button-down event is so that you can track mouse motion (by reading
motion events) until the button is released. *Note Motion Events::.
---------- Footnotes ----------
(1) Button-down is the conservative antithesis of drag.
File: elisp, Node: Repeat Events, Next: Motion Events, Prev: Button-Down Events, Up: Input Events
Repeat Events
-------------
If you press the same mouse button more than once in quick succession
without moving the mouse, Emacs generates special "repeat" mouse events
for the second and subsequent presses.
The most common repeat events are "double-click" events. Emacs
generates a double-click event when you click a button twice; the event
happens when you release the button (as is normal for all click events).
The event type of a double-click event contains the prefix
`double-'. Thus, a double click on the second mouse button with meta
held down comes to the Lisp program as `M-double-mouse-2'. If a
double-click event has no binding, the binding of the corresponding
ordinary click event is used to execute it. Thus, you need not pay
attention to the double click feature unless you really want to.
When the user performs a double click, Emacs generates first an
ordinary click event, and then a double-click event. Therefore, you
must design the command binding of the double click event to assume
that the single-click command has already run. It must produce the
desired results of a double click, starting from the results of a
single click.
This is convenient, if the meaning of a double click somehow "builds
on" the meaning of a single click--which is recommended user interface
design practice for double clicks.
If you click a button, then press it down again and start moving the
mouse with the button held down, then you get a "double-drag" event
when you ultimately release the button. Its event type contains
`double-drag' instead of just `drag'. If a double-drag event has no
binding, Emacs looks for an alternate binding as if the event were an
ordinary drag.
Before the double-click or double-drag event, Emacs generates a
"double-down" event when the user presses the button down for the
second time. Its event type contains `double-down' instead of just
`down'. If a double-down event has no binding, Emacs looks for an
alternate binding as if the event were an ordinary button-down event.
If it finds no binding that way either, the double-down event is
ignored.
To summarize, when you click a button and then press it again right
away, Emacs generates a down event and a click event for the first
click, a double-down event when you press the button again, and finally
either a double-click or a double-drag event.
If you click a button twice and then press it again, all in quick
succession, Emacs generates a "triple-down" event, followed by either a
"triple-click" or a "triple-drag". The event types of these events
contain `triple' instead of `double'. If any triple event has no
binding, Emacs uses the binding that it would use for the corresponding
double event.
If you click a button three or more times and then press it again,
the events for the presses beyond the third are all triple events.
Emacs does not have separate event types for quadruple, quintuple, etc.
events. However, you can look at the event list to find out precisely
how many times the button was pressed.
- Function: event-click-count EVENT
This function returns the number of consecutive button presses
that led up to EVENT. If EVENT is a double-down, double-click or
double-drag event, the value is 2. If EVENT is a triple event,
the value is 3 or greater. If EVENT is an ordinary mouse event
(not a repeat event), the value is 1.
- Variable: double-click-time
To generate repeat events, successive mouse button presses must be
at the same screen position, and the number of milliseconds between
successive button presses must be less than the value of
`double-click-time'. Setting `double-click-time' to `nil'
disables multi-click detection entirely. Setting it to `t'
removes the time limit; Emacs then detects multi-clicks by
position only.
File: elisp, Node: Motion Events, Next: Focus Events, Prev: Repeat Events, Up: Input Events
Motion Events
-------------
Emacs sometimes generates "mouse motion" events to describe motion
of the mouse without any button activity. Mouse motion events are
represented by lists that look like this:
(mouse-movement
(WINDOW BUFFER-POS (X . Y) TIMESTAMP))
The second element of the list describes the current position of the
mouse, just as in a click event (*note Click Events::.).
The special form `track-mouse' enables generation of motion events
within its body. Outside of `track-mouse' forms, Emacs does not
generate events for mere motion of the mouse, and these events do not
appear.
- Special Form: track-mouse BODY...
This special form executes BODY, with generation of mouse motion
events enabled. Typically BODY would use `read-event' to read the
motion events and modify the display accordingly.
When the user releases the button, that generates a click event.
Typically, BODY should return when it sees the click event, and
discard that event.
File: elisp, Node: Focus Events, Next: Misc Events, Prev: Motion Events, Up: Input Events
Focus Events
------------
Window systems provide general ways for the user to control which
window gets keyboard input. This choice of window is called the
"focus". When the user does something to switch between Emacs frames,
that generates a "focus event". The normal definition of a focus event,
in the global keymap, is to select a new frame within Emacs, as the user
would expect. *Note Input Focus::.
Focus events are represented in Lisp as lists that look like this:
(switch-frame NEW-FRAME)
where NEW-FRAME is the frame switched to.
Most X window managers are set up so that just moving the mouse into
a window is enough to set the focus there. Emacs appears to do this,
because it changes the cursor to solid in the new frame. However, there
is no need for the Lisp program to know about the focus change until
some other kind of input arrives. So Emacs generates a focus event only
when the user actually types a keyboard key or presses a mouse button in
the new frame; just moving the mouse between frames does not generate a
focus event.
A focus event in the middle of a key sequence would garble the
sequence. So Emacs never generates a focus event in the middle of a key
sequence. If the user changes focus in the middle of a key
sequence--that is, after a prefix key--then Emacs reorders the events
so that the focus event comes either before or after the multi-event key
sequence, and not within it.
File: elisp, Node: Misc Events, Next: Event Examples, Prev: Focus Events, Up: Input Events
Miscellaneous Window System Events
----------------------------------
A few other event types represent occurrences within the window
system.
`(delete-frame (FRAME))'
This kind of event indicates that the user gave the window manager
a command to delete a particular window, which happens to be an
Emacs frame.
The standard definition of the `delete-frame' event is to delete
FRAME.
`(iconify-frame (FRAME))'
This kind of event indicates that the user iconified FRAME using
the window manager. Its standard definition is `ignore'; since the
frame has already been iconified, Emacs has no work to do. The
purpose of this event type is so that you can keep track of such
events if you want to.
`(make-frame-visible (FRAME))'
This kind of event indicates that the user deiconified FRAME using
the window manager. Its standard definition is `ignore'; since the
frame has already been made visible, Emacs has no work to do.
If one of these events arrives in the middle of a key sequence--that
is, after a prefix key--then Emacs reorders the events so that this
event comes either before or after the multi-event key sequence, not
within it.
File: elisp, Node: Event Examples, Next: Classifying Events, Prev: Misc Events, Up: Input Events
Event Examples
--------------
If the user presses and releases the left mouse button over the same
location, that generates a sequence of events like this:
(down-mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864320))
(mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864180))
While holding the control key down, the user might hold down the
second mouse button, and drag the mouse from one line to the next.
That produces two events, as shown here:
(C-down-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219))
(C-drag-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219)
(#<window 18 on NEWS> 3510 (0 . 28) -729648))
While holding down the meta and shift keys, the user might press the
second mouse button on the window's mode line, and then drag the mouse
into another window. That produces a pair of events like these:
(M-S-down-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844))
(M-S-drag-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844)
(#<window 20 on carlton-sanskrit.tex> 161 (33 . 3)
-453816))
File: elisp, Node: Classifying Events, Next: Accessing Events, Prev: Event Examples, Up: Input Events
Classifying Events
------------------
Every event has an "event type", which classifies the event for key
binding purposes. For a keyboard event, the event type equals the
event value; thus, the event type for a character is the character, and
the event type for a function key symbol is the symbol itself. For
events that are lists, the event type is the symbol in the CAR of the
list. Thus, the event type is always a symbol or a character.
Two events of the same type are equivalent where key bindings are
concerned; thus, they always run the same command. That does not
necessarily mean they do the same things, however, as some commands look
at the whole event to decide what to do. For example, some commands use
the location of a mouse event to decide where in the buffer to act.
Sometimes broader classifications of events are useful. For example,
you might want to ask whether an event involved the META key,
regardless of which other key or mouse button was used.
The functions `event-modifiers' and `event-basic-type' are provided
to get such information conveniently.
- Function: event-modifiers EVENT
This function returns a list of the modifiers that EVENT has. The
modifiers are symbols; they include `shift', `control', `meta',
`alt', `hyper' and `super'. In addition, the modifiers list of a
mouse event symbol always contains one of `click', `drag', and
`down'.
The argument EVENT may be an entire event object, or just an event
type.
Here are some examples:
(event-modifiers ?a)
=> nil
(event-modifiers ?\C-a)
=> (control)
(event-modifiers ?\C-%)
=> (control)
(event-modifiers ?\C-\S-a)
=> (control shift)
(event-modifiers 'f5)
=> nil
(event-modifiers 's-f5)
=> (super)
(event-modifiers 'M-S-f5)
=> (meta shift)
(event-modifiers 'mouse-1)
=> (click)
(event-modifiers 'down-mouse-1)
=> (down)
The modifiers list for a click event explicitly contains `click',
but the event symbol name itself does not contain `click'.
- Function: event-basic-type EVENT
This function returns the key or mouse button that EVENT
describes, with all modifiers removed. For example:
(event-basic-type ?a)
=> 97
(event-basic-type ?A)
=> 97
(event-basic-type ?\C-a)
=> 97
(event-basic-type ?\C-\S-a)
=> 97
(event-basic-type 'f5)
=> f5
(event-basic-type 's-f5)
=> f5
(event-basic-type 'M-S-f5)
=> f5
(event-basic-type 'down-mouse-1)
=> mouse-1
- Function: mouse-movement-p OBJECT
This function returns non-`nil' if OBJECT is a mouse movement
event.
- Function: event-convert-list LIST
This function converts a list of modifier names and a basic event
type to an event type which specifies all of them. For example,
(event-convert-list '(control ?a))
=> 1
(event-convert-list '(control meta ?a))
=> -134217727
(event-convert-list '(control super f1))
=> C-s-f1
File: elisp, Node: Accessing Events, Next: Strings of Events, Prev: Classifying Events, Up: Input Events
Accessing Events
----------------
This section describes convenient functions for accessing the data in
a mouse button or motion event.
These two functions return the starting or ending position of a
mouse-button event. The position is a list of this form:
(WINDOW BUFFER-POSITION (X . Y) TIMESTAMP)
- Function: event-start EVENT
This returns the starting position of EVENT.
If EVENT is a click or button-down event, this returns the
location of the event. If EVENT is a drag event, this returns the
drag's starting position.
- Function: event-end EVENT
This returns the ending position of EVENT.
If EVENT is a drag event, this returns the position where the user
released the mouse button. If EVENT is a click or button-down
event, the value is actually the starting position, which is the
only position such events have.
These five functions take a position as described above, and return
various parts of it.
- Function: posn-window POSITION
Return the window that POSITION is in.
- Function: posn-point POSITION
Return the buffer position in POSITION. This is an integer.
- Function: posn-x-y POSITION
Return the pixel-based x and y coordinates in POSITION, as a cons
cell `(X . Y)'.
- Function: posn-col-row POSITION
Return the row and column (in units of characters) of POSITION, as
a cons cell `(COL . ROW)'. These are computed from the X and Y
values actually found in POSITION.
- Function: posn-timestamp POSITION
Return the timestamp in POSITION.
- Function: scroll-bar-event-ratio EVENT
This function returns the fractional vertical position of a scroll
bar event within the scroll bar. The value is a cons cell
`(PORTION . WHOLE)' containing two integers whose ratio is the
fractional position.
- Function: scroll-bar-scale RATIO TOTAL
This function multiplies (in effect) RATIO by TOTAL, rounding the
result to an integer. The argument RATIO is not a number, but
rather a pair `(NUM . DENOM)'--typically a value returned by
`scroll-bar-event-ratio'.
This function is handy for scaling a position on a scroll bar into
a buffer position. Here's how to do that:
(+ (point-min)
(scroll-bar-scale
(posn-x-y (event-start event))
(- (point-max) (point-min))))
Recall that scroll bar events have two integers forming ratio in
place of a pair of x and y coordinates.